﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>置字符串 - 语法 &amp; 使用 | AutoHotkey v2</title>
<meta name="description" content="The 置字符串 function copies a 字符串 to a memory address or buffer, optionally converting it to a given code page." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>置字符串</h1>

<p>复制字符串到内存地址或缓冲, 可选地将字符串转换到给定的代码页.</p>

<pre class="Syntax"><span class="func">置字符串</span> 字符串 <span class="optional">, Encoding := <i>None</i></span>
<span class="func">置字符串</span> 字符串, Target <span class="optional">, Length</span> <span class="optional">, Encoding := <i>None</i></span>
</pre>
<h2 id="Parameters">参数</h2>
<dl>

  <dt>字符串</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>任何字符串. 如果给定一个数字, 它将自动转换为字符串.</p>
    <p><em>字符串</em> 被假定为使用<a href="../Concepts.htm#string-encoding">原生编码</a>.</p>
  </dd>

  <dt>Target</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#objects">对象</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>类<a href="../objects/Buffer.htm">缓冲</a>对象或内存地址, 字符串将写入其中.</p>
    <p>可以使用任何实现 <a href="../objects/Buffer.htm#Ptr">Ptr</a> 和 <a href="../objects/Buffer.htm#Size">Size</a> 属性的对象, 但此函数针对原生的<a href="../objects/Buffer.htm">缓冲</a>对象进行了优化. 传递具有这些属性的对象可确保函数不会将内存写入无效位置; 这样做可能会导致崩溃或其他不可预测的行为.</p>
    <p class="warning"><strong>注意:</strong> 如果需要在代码页之间进行转换, 则所需的缓冲大小可能与源字符串的大小不同. 对于这种情况, 调用带有两个参数的 置字符串 来计算所需的大小.</p>
  </dd>

  <dt>Length</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>要写入的最大<a href="../Concepts.htm#character">字符</a>数, 需要时包含<a href="../Concepts.htm#null-termination">空终止符</a>.</p>
    <p>如果 <em>Length</em> 为 0 或小于转换后的计划长度(或不需要转换时, 源字符串的长度), 则抛出异常.</p>
    <p>除非已知缓冲大小足够大, 否则不能省略 <em>Length</em>, 例如, 如果缓冲是基于先前使用相同的 <em>Source</em> 和 <em>Encoding</em> 调用的 置字符串 而分配的.</p>
    <p class="warning"><strong>注意:</strong> 当指定 <em>Encoding</em> 时, <em>Length</em> 应该是缓冲的大小(以字符为单位), <strong>而不是</strong> <em>字符串</em> 或子字符串的长度, 因为转换可能会增加其长度.</p>
    <p class="warning"><strong>注意:</strong> <em>Length</em> 是以字符数来计算的, 而缓冲大小通常以字节度量, 置字符串 的返回值也是如此. 若要以字节为单位来指定缓冲大小, 请在 <em>Target</em> 参数中使用类<a href="../objects/Buffer.htm">缓冲</a>对象.</p>
  </dd>

  <dt>Encoding</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a>或<a href="../Concepts.htm#numbers">整数</a></p>
    <p>目标编码; 例如, <code>"UTF-8"</code>, <code>"UTF-16"</code> 或 <code>"CP936"</code>. 对于数字标识符, 只有在指定 <em>Length</em> 时, 才可以省略前缀 "CP". 指定空字符串或 <code>"CP0"</code> 则使用系统默认 ANSI 代码.</p>
  </dd>

</dl>

<h2 id="Return_Value">返回值</h2>
<p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
<p>函数返回写入的字节数. 如果没有指定 <i>Target</i>, 则返回以字节数表示的必须的缓冲大小. 如果 <em>Length</em> 准确等于源字符串的长度, 那么字符串不包含<a href="../Concepts.htm#null-termination">空终止符</a>; 否则返回的大小包含空终止符.</p>

<h2 id="Error_Handling">错误处理</h2>
<p>如果检测到无效参数或转换无法执行, 则抛出<a href="Catch.htm#RuntimeErrors">异常</a>.</p>

<h2 id="Remarks">备注</h2>
<p>注意, <i>字符串</i> 参数总是假定使用当前可执行文件的<a href="../Concepts.htm#string-encoding">原生编码</a>, 而 <i>Encoding</i> 指定写入给定 <i>Target</i> 的字符串的编码. 如果没有指定 <em>Encoding</em>, 则只测量或复制字符串, 而不进行任何转换.</p>

<h2 id="Related">相关</h2>
<p><a href="../Concepts.htm#string-encoding">字符编码</a>, <a href="StrGet.htm">获取字符串</a>, <a href="../Compat.htm">脚本兼容性</a>, <a href="FileEncoding.htm">设置文件编码</a>, <a href="DllCall.htm">动态库调用</a>, <a href="BufferAlloc.htm">创建缓冲区</a>, <a href="../objects/Buffer.htm">缓冲对象</a>, <a href="VarSetStrCapacity.htm">VarSetStrCapacity</a></p>

<h2 id="ex1">示例</h2>
<div class="ex" id="ExNumEnc">
<p><a href="#ExNumEnc">#1</a>: <em>Length</em> 或 <em>Encoding</em> 都可以直接在 <em>Target</em> 后面指定, 但在这种情况下 <em>Encoding</em> 必须是非数字的:</p>
<pre>
置字符串(str, address, "cp0")  <em>; 代码页 0, 未指定缓冲大小</em>
置字符串(str, address, n, 0)   <em>; 最大 n 字符, 代码页 0</em>
置字符串(str, address, 0)      <em>; 不支持(最大长度为 0 的字符)</em>
</pre>
</div>

<div class="ex" id="ExEncoding">
<p><a href="#ExEncoding">#2</a>: 可以调用一次 置字符串, 来计算特定编码中的字符串所需的缓冲大小, 然后再次对字符串进行编码并将其写入缓冲. 这个过程可以通过在你的<a href="../Functions.htm#lib">库</a>中添加以下函数来简化:</p>
<pre filename="StrBuf.ahk"><em>; 返回包含字符串的<a href="../objects/Buffer.htm">缓冲</a>对象.</em>
StrBuf(字符串, encoding)
{
    <em>; 计算所需的大小并分配缓冲.</em>
    buf := 创建缓冲区(置字符串(字符串, encoding))
    <em>; 复制或转换字符串.</em>
    置字符串(字符串, buf, encoding)
    返回 buf
}</pre>
</div>

</body>
</html>